Cognitive Psychology Brownbag: R Markdown for Graduate Students

Holly Zaharchuk

February 19, 2020

What is R Markdown?

  • Markup language
  • R Markdown != R

Parts of an R Markdown document

  1. YAML header
  2. Markup
  3. Code chunks

YAML header

Global options for outputs/formatting

YAML example

Markup

Plain text formatting allows for conversion to multiple document types

Markdown example

Code chunks

# This is a chunk of R code that adds an image
knitr::include_graphics("images/example_chunk.png")

Creating output

Output types

  • PDF: requires \(\LaTeX\) to compile (TinyTeX distribution)
  • HTML
  • Microsoft Office (Word/Powerpoint)

YAML specification

  • Use output argument in YAML header
  • Pay attention to indentation and colons
  • Press knit button or command/CTRL-shift-K

Render

Render files in the console with rmarkdown::render(file, output_format) (this is what knit is doing)

Option to create PDF from HTML with pagedown::chrome_print(file)

Using output templates

  1. Built-in templates
  2. Templates from R packages
  3. User-defined templates

Built-in templates

  • Presentations
    • ioslides and Slidy for HTML
    • Beamer for PDF
  • Shiny documents and presentations (interactive)

R packages

User-defined templates

\(\LaTeX\) templates (pay attention to $ in templates) LaTeX example

User-defined templates

Word Document: use the Styles Pane and “Update to Match Selection” Word example

Formatting

  1. YAML parameters and references
  2. Inline \(\LaTeX\) and CSS code
  3. Custom edits to templates

YAML parameters

YAML references

These files go in the same place as your .Rmd

  • Bibliography: .bib (I use BibDesk for my reference manager)
  • Citation style language files: .csl (see my CV and Psychonomics poster repos for customized APA 6 files)
  • \(\LaTeX\) styling: .cls
  • HTML styling: .css
  • Interacting with pandoc: .lua (multiple bibliographies)

YAML references

Example from my CV with both template-specific YAML parameters and YAML references

Inline \(\LaTeX\)  and CSS code

  • \(\LaTeX\) with PDFs
    • Calling \(\LaTeX\) packages
    • Using symbols: useful lists here and here
    • Using type-setting commands (e.g., \vspace{12pt})
  • CSS with HTML

\(\LaTeX\)

Examples of calling packages in the YAML header and using inline functions from my stats homework

\(\LaTeX\)

Stats homework output

LaTeX example output

CSS/HTML

Examples from my Psychonomics poster

CSS formatting example HTML formatting example

Editing templates

To make extremely custom edits to templates, sometimes you have to edit the template documents

  1. Find out where your computer stores your R packages and edit the template there
  2. If the template generates a style document (e.g., .cls) in the directory with your .Rmd file, you can usually edit that without going to the package

Package documents

# Make dataframe with installed packages
pkgs <- installed.packages() %>%
  as.data.frame()

# Pull posterdown package 
pstr <- pkgs %>% 
  select(Package, LibPath, Version, Depends, Imports) %>%
  dplyr::filter(Package == "posterdown")

# Make table
kable(pstr) %>%
  kable_styling(bootstrap_options = "condensed", 
                font_size = 18)
Package LibPath Version Depends Imports
posterdown /Library/Frameworks/R.framework/Versions/3.5/Resources/library 1.0 NA pagedown, rmarkdown, yaml

Package documents

  • Save the original template and move it to a different location
  • Make one change at a time
  • Name the updated template with the same name in the same place as the original

Directory documents

Knitting the vitae::awesomecv template created a .cls file that I could edit to change font sizes/colors

Trouble-shooting

Identifying issues

  • Warnings vs. errors
  • Console vs. chunk
  • Markdown environment vs. R environment
  • Package specification :: for unloaded packages and conflicting functions

Warnings

Warnings won’t stop your document from compiling, but generally indicate that you should change something in your code

Warning example

Errors

Chunk error Error example

Markdown/YAML error Error example

R code and environments

Running a chunk executes the code in the console and adds the output to your R environment

R code and environments

Your R environment is separate from the environment created when “knitting” a document

y <- 100
# print(x + y) works when I run this chunk, but fails when knitting

Tips

  • Clear all variables: rm(ls = list())
  • Restart R environment: control/CTRL + fn + shift + F10
  • Run all chunks individually in order before compiling to test code
  • Search for information
    • Use Help window
    • Search for package in console with ?package
    • Google package and error

Stack Overflow is your friend!

Takeaways

  1. YAML header: define output types, templates, and additional parameters (e.g., bibliography)
  2. Setup chunk: define global chunk options
  3. Markup: add information/description and control local text behavior with \(\LaTeX\)/CSS (depending on output)
  4. Chunks: add R code and control local chunk behavior

Random tidbits

  • Escape characters with a backslash \
  • Call R objects and functions in Markdown/YAML by ~sandwiching~ with backticks ``
  • Automatic bracket/quote/asterisk wrapping
  • Dollar signs for \(\LaTeX\) math mode (but also be careful with pandoc)
  • Line spacing matters in markup

Reference documents

Other packages/tools

Updating software/packages

  • Update your TeX distribution from the command line
  • Update all packages (including rmarkdown) in library with update.packages(path)
  • Update individual packages by reinstalling with install.packages(package)
  • Update R in the console with updateR package
  • Redownload RStudio to update

Pause

Questions?

R Stuff

  • Regular expressions for working with free response text (cheat sheet here)
  • assign() function for dynamic variable names
  • Store ggplot parameters in a list()
  • source()
  • %notin%

Keys to success

  • Treat your data as read-only
  • Comment your code excessively
  • Keep chunks small

R Markdown